Reading
CIFTI files organize the gray matter of the brain into “grayordinates”: vertices representing the left and right cortical surfaces, and voxels representing the subcortical gray matter structures and the cerebellum. A CIFTI file consists of two parts: (1) an XML header which contains all the metadata including medial wall locations, subcortical structure labels, and the subcortical volumetric mask; and (2) a NIFTI format matrix representing all the grayordinate data. These components are read in together with read_cifti:
basename(cifti_fnames["dtseries"])
## [1] "Conte69.MyelinAndCorrThickness.32k_fs_LR.dtseries.nii"
xii <- read_xifti(cifti_fnames["dtseries"])
The result of read_cifti is a "xifti" object. We can get an overview of it using its summary S3 method:
xii # same as `summary(xii)`
## ====CIFTI METADATA===================
## Intent: 3002 (dtseries)
## - time step 1 (seconds)
## - time start 0
## Measurements: 2 columns
##
## ====BRAIN STRUCTURES=================
## - left cortex 30424 data vertices
## 2068 medial wall vertices (32492 total)
##
## - right cortex 30527 data vertices
## 1965 medial wall vertices (32492 total)
By default, read_cifti only reads in the left and right cortex data. The subcortical data can be included by using the argument brainstructures="all". Other brainstructure combinations can be specified too, e.g. brainstructures=c("left", "subcortical"). The full set of choices for brainstructures is any combination of "left", "right" and "subcortical", or "all" for all three.
"xifti" objects are lists with entries data (the grayordinate data matrix, separated by brainstructure), surf (surface geometry), and meta (metadata, most of which is from the NIFTI XML header). surf distinguishes a "xifti" from a CIFTI file: the left and right cortical surface geometries are not included in CIFTI files, so they must be read from separate surface GIFTI files (ending in surf.gii). The surface must be compatible: the number of vertices must be the same, and each vertex in the CIFTI data must correspond to the vertex location in the corresponding GIFTI surface file. In this way, a "xifti" represents a combination of a CIFTI file with compatible GIFTI files for the cortical mesh.
We can add GIFTI surface geometries with add_surf:
xii <- add_surf(xii, surfL=surfL_fname, surfR=surfR_fname)
xii
## ====CIFTI METADATA===================
## Intent: 3002 (dtseries)
## - time step 1 (seconds)
## - time start 0
## Measurements: 2 columns
##
## ====BRAIN STRUCTURES=================
## - left cortex 30424 data vertices
## 2068 medial wall vertices (32492 total)
## left surface geometry is present
##
## - right cortex 30527 data vertices
## 1965 medial wall vertices (32492 total)
## right surface geometry is present
Alternatively, we could have provided the surface geometries at the outset of reading the CIFTI file:
xii2 <- read_xifti(cifti_fnames["dtseries"], surfL_fname=surfL_fname, surfR_fname=surfR_fname)
all.equal(xii, xii2) # same result
## [1] TRUE
To only read the CIFTI header, use info_cifti. Let’s read the header of the dscalar file:
xii_info <- ciftiTools::info_cifti(cifti_fnames["dscalar"])
str(xii_info, nchar.max=50) # shows header structure
## List of 3
## $ cortex :List of 2
## ..$ medial_wall_mask:List of 2
## .. ..$ left : logi [1:5762] TRUE TRUE TRUE TRUE TRUE TRUE ...
## .. ..$ right: logi [1:5762] TRUE TRUE TRUE TRUE TRUE TRUE ...
## ..$ resamp_res : NULL
## $ subcort:List of 3
## ..$ labels : NULL
## ..$ mask : NULL
## ..$ trans_mat: NULL
## $ cifti :List of 4
## ..$ intent : num 3006
## ..$ brainstructures: chr [1:2] "left" "right"
## ..$ names : chr [1:2] "MyelinMap_BC_decurv" "corrThickness"
## ..$ misc :List of 4
## .. ..$ ParentProvenance : chr "C:\\Users\\damon\\AppData\\Local\"| __truncated__
## .. ..$ ProgramProvenance: chr "Connectome Workbench\nType: Comma"| __truncated__
## .. ..$ Provenance : chr "C:\\Users\\damon\\Desktop\\WORKBE"| __truncated__
## .. ..$ WorkingDirectory : chr "C:/Users/damon/Desktop/ciftiTools/vignettes"
To read in only certain columns of a CIFTI file, use the idx argument:
read_xifti(cifti_fnames["dtseries"], idx=2) # second column only
## ====CIFTI METADATA===================
## Intent: 3002 (dtseries)
## - time step 1 (seconds)
## - time start 0
## Measurements: 1 column
##
## ====BRAIN STRUCTURES=================
## - left cortex 30424 data vertices
## 2068 medial wall vertices (32492 total)
##
## - right cortex 30527 data vertices
## 1965 medial wall vertices (32492 total)
Writing
When a "xifti" object is written to files, the CIFTI components are placed in a CIFTI file and the surface geometries, if any, are placed in GIFTI files.
out_dir <- "output"
write_xifti(
xii,
file.path(out_dir, "my_cifti.dtseries.nii"),
file.path(out_dir, "my_L.surf.gii"), file.path(out_dir, "my_R.surf.gii")
)
## Writing left cortex.
## Writing right cortex.
## Creating CIFTI file from separated components.
## Writing surface geometry GIFTI(s).
With separate_cifti, a CIFTI can be separated and written into its component parts: the cortical data can be written to GIFTI metric or label files, and the subcortical data can be written to a NIFTI file. In addition, any ROIs or labels will also be written to files. The files are automatically named unless a new file name is provided.
# Use default names for everything except left cortex
separated_fnames = separate_cifti(
cifti_fnames["dscalar_ones"], brainstructures="all",
cortexL_fname="my_left_cortex.func.gii", write_dir = out_dir
)
# Files written to `out_dir`, or current working dir. if not specified
basename(separated_fnames)
## [1] "my_left_cortex.func.gii" "ones_1k.ROI_L.func.gii"
## [3] "ones_1k.R.func.gii" "ones_1k.ROI_R.func.gii"
## [5] "ones_1k.nii" "ones_1k.labels.nii"
## [7] "ones_1k.ROI.nii"
Separated files can be read into R with the oro.nifti, RNifti, and gifti packages, and combined into a "xifti" object with as.xifti.
